Quarto Theming and Styling

quarto

theming

styling

css

scss

design

Comprehensive guide to Quarto’s theming system, from built-in themes to custom styling approaches

Author

Dario Airoldi

Published

January 16, 2025

Modified

November 3, 2025

Abstract

A comprehensive guide covering all aspects of Quarto’s theming and styling capabilities. This document explores built-in themes, custom CSS integration, SCSS variables, Bootstrap integration, typography, color schemes, responsive design, dark mode support, and performance considerations. Essential for creating visually appealing and professionally designed Quarto documentation websites.

Keywords

quarto, theming, styling, css, scss, bootstrap, design, customization

1 📋 Table of Contents

📖 Overview
🎨 Built-in Themes
⚙️ Theme Configuration
🎨 Custom CSS Integration
📊 SCSS Variables and Customization
🅱️ Bootstrap Integration
📐 Layout Customization
🔤 Typography and Fonts
🌈 Color Schemes
📱 Responsive Design
🌙 Dark Mode Support
🧩 Custom Components
🏷️ Brand Integration
⚡ Performance Considerations
✅ Best Practices
📚 Resources

2 📖 Overview

Quarto provides extensive theming and styling capabilities that allow you to create visually appealing and professionally designed documentation websites. This guide covers all aspects of Quarto’s theming system, from built-in themes to custom styling approaches.

3 🎨 Built-in Themes

Quarto comes with a variety of professionally designed themes based on Bootstrap and Bootswatch.

3.1 Available Themes

format:
  html:
    theme: default    # Clean, minimal design
    # theme: cerulean  # Blue accent theme
    # theme: cosmo     # Flat, modern design
    # theme: cyborg    # Dark theme with cyan accents
    # theme: darkly    # Dark Bootstrap theme
    # theme: flatly    # Flat UI theme
    # theme: journal   # Newspaper-style theme
    # theme: litera    # Typography-focused theme
    # theme: lumen     # Light theme with warm colors
    # theme: lux       # Elegant theme with serif fonts
    # theme: materia   # Material Design inspired
    # theme: minty     # Fresh, green accent theme
    # theme: morph     # Modern, rounded design
    # theme: pulse     # Purple accent theme
    # theme: quartz    # Professional, clean theme
    # theme: sandstone # Warm, earthy theme
    # theme: simplex   # Minimalist theme
    # theme: sketchy   # Hand-drawn, casual style
    # theme: slate     # Dark theme with cool colors
    # theme: solar     # Solarized color scheme
    # theme: spacelab  # Space-themed design
    # theme: superhero # Dark theme with bright accents
    # theme: united    # Orange accent theme
    # theme: vapor     # Retro, neon-inspired theme
    # theme: yeti      # Clean theme with blue accents
    # theme: zephyr    # Light, airy design

3.2 Theme Selection Guidelines

Default: Best for general documentation
Cosmo: Modern, professional look
Flatly: Clean, contemporary design
Darkly/Cyborg: Dark themes for developers
Journal: Academic/research content
Lux: Elegant, serif-based design
Materia: Material Design aesthetic

4 ⚙️ Theme Configuration

4.1 Basic Theme Setup

# _quarto.yml
project:
  type: website

format:
  html:
    theme: cosmo
    css: custom.css
    toc: true
    code-fold: true

4.2 Multiple Theme Options

format:
  html:
    theme: 
      - cosmo
      - custom.scss
    css: 
      - styles.css
      - components.css

4.3 Theme-Specific Configuration

format:
  html:
    theme: cosmo
    mainfont: "Open Sans"
    monofont: "Fira Code"
    fontsize: 1.1em
    linestretch: 1.7

5 🎨 Custom CSS Integration

5.1 Basic CSS Integration

Create a styles.css file:

/* Custom styles for Quarto site */
:root {
  --primary-color: #3498db;
  --secondary-color: #2c3e50;
  --accent-color: #e74c3c;
  --background-color: #ffffff;
  --text-color: #2c3e50;
}

body {
  font-family: 'Inter', sans-serif;
  color: var(--text-color);
  background-color: var(--background-color);
}

.navbar {
  background-color: var(--primary-color) !important;
}

.btn-primary {
  background-color: var(--accent-color);
  border-color: var(--accent-color);
}

5.2 Advanced CSS Customization

/* Typography improvements */
h1, h2, h3, h4, h5, h6 {
  font-weight: 600;
  line-height: 1.2;
  margin-top: 2rem;
  margin-bottom: 1rem;
}

/* Code styling */
pre {
  background-color: #f8f9fa;
  border: 1px solid #e9ecef;
  border-radius: 0.375rem;
  padding: 1rem;
}

code {
  background-color: #f1f3f4;
  padding: 0.125rem 0.25rem;
  border-radius: 0.25rem;
  font-size: 0.875em;
}

/* Callout customization */
.callout {
  border-left: 4px solid var(--primary-color);
  padding: 1rem;
  margin: 1.5rem 0;
  background-color: #f8f9fa;
}

.callout-title {
  font-weight: 600;
  color: var(--primary-color);
}

6 📊 SCSS Variables and Customization

6.1 Creating Custom SCSS Theme

Create a custom.scss file:

/*-- scss:defaults --*/
// Import Google Fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

// Color palette
$primary: #3498db;
$secondary: #95a5a6;
$success: #27ae60;
$info: #17a2b8;
$warning: #f39c12;
$danger: #e74c3c;
$light: #f8f9fa;
$dark: #2c3e50;

// Typography
$font-family-sans-serif: 'Inter', system-ui, -apple-system, sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Layout
$grid-breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
  xxl: 1400px
);

/*-- scss:rules --*/
// Custom component styles
.hero-section {
  background: linear-gradient(135deg, $primary, darken($primary, 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  h1 {
    font-size: 3rem;
    font-weight: 700;
    margin-bottom: 1rem;
  }
  
  .lead {
    font-size: 1.25rem;
    margin-bottom: 2rem;
  }
}

.feature-card {
  background: white;
  border-radius: 0.5rem;
  padding: 2rem;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  transition: transform 0.3s ease;
  
  &:hover {
    transform: translateY(-5px);
  }
  
  .icon {
    font-size: 3rem;
    color: $primary;
    margin-bottom: 1rem;
  }
}

6.2 SCSS Variables Reference

// Brand colors
$primary: #your-brand-color;
$secondary: #your-secondary-color;

// Typography
$headings-font-family: 'Your-Heading-Font', sans-serif;
$font-family-base: 'Your-Body-Font', sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Spacing
$spacer: 1rem;
$spacers: (
  0: 0,
  1: $spacer * 0.25,
  2: $spacer * 0.5,
  3: $spacer,
  4: $spacer * 1.5,
  5: $spacer * 3
);

// Borders
$border-radius: 0.375rem;
$border-width: 1px;
$border-color: #dee2e6;

7 🅱️ Bootstrap Integration

7.1 Bootstrap Classes in Markdown

::: {.container-fluid}

::::{.row}

:::{.col-md-8}
### Main Content
Content goes here
:::

:::{.col-md-4}
### Sidebar
Sidebar content
:::

::::

:::

::: {.alert .alert-info}
**Info:** This is an informational alert using Bootstrap classes.
:::

::: {.btn .btn-primary .btn-lg}
[Large Primary Button](#)
:::

7.2 Custom Bootstrap Components

/* Custom button variants */
.btn-outline-custom {
  color: var(--primary-color);
  border-color: var(--primary-color);
}

.btn-outline-custom:hover {
  color: white;
  background-color: var(--primary-color);
  border-color: var(--primary-color);
}

/* Custom card styles */
.card-hover {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card-hover:hover {
  transform: translateY(-5px);
  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
}

/* Custom navbar styles */
.navbar-custom {
  background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
}

8 📐 Layout Customization

8.1 Custom Page Layouts

# In document front matter
---
title: "Custom Layout Page"
format:
  html:
    page-layout: custom
    css: page-styles.css
---

8.2 Grid System Customization

// Custom grid system
.custom-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 2rem;
  padding: 2rem 0;
}

.grid-item {
  background: white;
  padding: 1.5rem;
  border-radius: 0.5rem;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// Responsive adjustments
@media (max-width: 768px) {
  .custom-grid {
    grid-template-columns: 1fr;
    gap: 1rem;
    padding: 1rem 0;
  }
}

8.3 Header and Footer Customization

<!-- custom-header.html -->
<header class="site-header">
  <div class="container">
    <nav class="navbar navbar-expand-lg">
      <a class="navbar-brand" href="/">
        <img src="logo.svg" alt="Logo" height="40">
      </a>
      <!-- Navigation items -->
    </nav>
  </div>
</header>

9 🔤 Typography and Fonts

9.1 Font Configuration

format:
  html:
    theme: cosmo
    mainfont: "Source Sans Pro"
    monofont: "JetBrains Mono"
    fontsize: 1.1em
    linestretch: 1.7

9.2 Custom Font Integration

// Import fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@300;400;500&display=swap');

// Font variables
$font-family-base: 'Inter', system-ui, sans-serif;
$font-family-monospace: 'JetBrains Mono', 'SF Mono', Consolas, monospace;

// Typography scale
$font-sizes: (
  xs: 0.75rem,
  sm: 0.875rem,
  base: 1rem,
  lg: 1.125rem,
  xl: 1.25rem,
  2xl: 1.5rem,
  3xl: 1.875rem,
  4xl: 2.25rem,
  5xl: 3rem
);

// Apply typography
body {
  font-family: $font-family-base;
  font-size: map-get($font-sizes, base);
  line-height: 1.6;
}

h1 { font-size: map-get($font-sizes, 4xl); }
h2 { font-size: map-get($font-sizes, 3xl); }
h3 { font-size: map-get($font-sizes, 2xl); }

10 🌈 Color Schemes

10.1 Defining Color Palettes

// Primary palette
$colors: (
  "primary": #3498db,
  "secondary": #95a5a6,
  "accent": #e74c3c,
  "success": #27ae60,
  "warning": #f39c12,
  "danger": #e74c3c,
  "info": #17a2b8,
  "light": #f8f9fa,
  "dark": #2c3e50
);

// Generate utility classes
@each $name, $color in $colors {
  .text-#{$name} {
    color: $color !important;
  }
  
  .bg-#{$name} {
    background-color: $color !important;
  }
  
  .border-#{$name} {
    border-color: $color !important;
  }
}

10.2 Semantic Color Usage

/* Semantic color system */
:root {
  /* Brand colors */
  --brand-primary: #3498db;
  --brand-secondary: #2c3e50;
  
  /* Semantic colors */
  --color-success: #27ae60;
  --color-warning: #f39c12;
  --color-error: #e74c3c;
  --color-info: #17a2b8;
  
  /* Neutral colors */
  --color-text: #2c3e50;
  --color-text-muted: #6c757d;
  --color-background: #ffffff;
  --color-surface: #f8f9fa;
  --color-border: #dee2e6;
}

11 📱 Responsive Design

11.1 Responsive Typography

// Responsive font sizes
@mixin responsive-font-size($min-size, $max-size) {
  font-size: clamp(#{$min-size}, 4vw, #{$max-size});
}

h1 {
  @include responsive-font-size(2rem, 4rem);
  font-weight: 700;
  line-height: 1.1;
}

h2 {
  @include responsive-font-size(1.5rem, 3rem);
  font-weight: 600;
  line-height: 1.2;
}

// Responsive spacing
@media (max-width: 768px) {
  .container {
    padding-left: 1rem;
    padding-right: 1rem;
  }
  
  .section {
    padding-top: 2rem;
    padding-bottom: 2rem;
  }
}

11.2 Mobile-First Approach

// Mobile-first responsive design
.feature-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
  
  @media (min-width: 576px) {
    grid-template-columns: repeat(2, 1fr);
    gap: 1.5rem;
  }
  
  @media (min-width: 992px) {
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;
  }
}

12 🌙 Dark Mode Support

12.1 Dark Mode Configuration

format:
  html:
    theme: 
      light: cosmo
      dark: darkly

12.2 Custom Dark Mode Styles

// Dark mode variables
[data-bs-theme="dark"] {
  --color-background: #1a1a1a;
  --color-surface: #2d2d2d;
  --color-text: #ffffff;
  --color-text-muted: #a0a0a0;
  --color-border: #404040;
}

// Dark mode specific styles
@media (prefers-color-scheme: dark) {
  .custom-component {
    background-color: var(--color-surface);
    color: var(--color-text);
    border-color: var(--color-border);
  }
}

13 🧩 Custom Components

13.1 Creating Reusable Components

// Hero section component
.hero {
  background: linear-gradient(135deg, var(--brand-primary), darken(var(--brand-primary), 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  &__title {
    font-size: 3.5rem;
    font-weight: 700;
    margin-bottom: 1rem;
    
    @media (max-width: 768px) {
      font-size: 2.5rem;
    }
  }
  
  &__subtitle {
    font-size: 1.25rem;
    opacity: 0.9;
    margin-bottom: 2rem;
  }
  
  &__cta {
    display: inline-flex;
    gap: 1rem;
    margin-top: 1rem;
  }
}

// Card component
.feature-card {
  background: white;
  border-radius: 0.75rem;
  padding: 2rem;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05);
  transition: all 0.3s ease;
  
  &:hover {
    transform: translateY(-4px);
    box-shadow: 0 12px 25px rgba(0, 0, 0, 0.1);
  }
  
  &__icon {
    width: 4rem;
    height: 4rem;
    background: var(--brand-primary);
    border-radius: 50%;
    display: flex;
    align-items: center;
    justify-content: center;
    margin-bottom: 1.5rem;
    
    svg {
      width: 2rem;
      height: 2rem;
      fill: white;
    }
  }
  
  &__title {
    font-size: 1.25rem;
    font-weight: 600;
    margin-bottom: 0.75rem;
  }
  
  &__description {
    color: var(--color-text-muted);
    line-height: 1.6;
  }
}

14 🏷️ Brand Integration

14.1 Brand Configuration

// Brand system
$brand-colors: (
  primary: #your-primary-color,
  secondary: #your-secondary-color,
  accent: #your-accent-color
);

$brand-fonts: (
  heading: 'Your-Brand-Font',
  body: 'Your-Body-Font',
  mono: 'Your-Mono-Font'
);

// Logo integration
.site-logo {
  height: 2.5rem;
  width: auto;
  
  @media (max-width: 768px) {
    height: 2rem;
  }
}

// Brand-consistent spacing
$brand-spacing: (
  xs: 0.25rem,
  sm: 0.5rem,
  md: 1rem,
  lg: 1.5rem,
  xl: 2rem,
  xxl: 3rem
);

14.2 Style Guide Implementation

// Style guide components
.style-guide {
  &__color-swatch {
    width: 100px;
    height: 100px;
    border-radius: 0.5rem;
    display: flex;
    align-items: center;
    justify-content: center;
    color: white;
    font-weight: 600;
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
  }
  
  &__typography-sample {
    margin-bottom: 2rem;
    
    h1, h2, h3, h4, h5, h6 {
      margin-bottom: 0.5rem;
    }
  }
}

15 ⚡ Performance Considerations

15.1 CSS Optimization

// Efficient CSS practices
.component {
  // Use efficient selectors
  &__element {
    // Avoid deep nesting
  }
  
  // Use CSS custom properties for theming
  background-color: var(--component-bg, #ffffff);
  color: var(--component-text, #333333);
}

// Minimize unused CSS
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

// Only import needed components
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/utilities";

15.2 Loading Optimization

format:
  html:
    theme: cosmo
    css: 
      - href: styles.css
        preload: true
    include-in-header: |
      <link rel="preconnect" href="https://fonts.googleapis.com">
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

16 ✅ Best Practices

16.1 1. Design System Approach

Consistency: Use a consistent color palette and typography
Modularity: Create reusable component styles
Documentation: Document your design decisions
Accessibility: Ensure sufficient color contrast and readability

16.2 2. Performance

Minimize CSS: Only include necessary styles
Optimize Images: Use appropriate formats and sizes
Font Loading: Use font-display: swap for better performance
Critical CSS: Inline critical styles for faster rendering

16.3 3. Maintainability

Variables: Use CSS custom properties or SCSS variables
Organization: Structure CSS with clear naming conventions
Comments: Document complex styles and calculations
Version Control: Track changes to design system

16.4 4. Responsive Design

Mobile First: Design for mobile devices first
Progressive Enhancement: Add features for larger screens
Touch Targets: Ensure interactive elements are appropriately sized
Content Priority: Prioritize important content on smaller screens

16.5 5. Accessibility

Color Contrast: Maintain WCAG AA standards (4.5:1 ratio)
Focus States: Provide clear focus indicators
Screen Readers: Use semantic HTML and ARIA labels
Motion: Respect prefers-reduced-motion settings

17 📚 Resources

This comprehensive guide covers all aspects of Quarto theming and styling, from basic theme selection to advanced custom component creation. Use these techniques to create professional, branded documentation that reflects your organization’s visual identity.